3장 설치하고 환경 맞추기 (입문판)

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 5가지만 기억하면 됩니다. 1. 클로드 코드는 지금 쓰던 환경을 안 건드리고 옆에 얹는 도구예요. 2. 설치 전에 Node.js와 npm이라는 준비물 두 개가 필요해요. 3. macOS는 곧장 설치, Windows는 WSL이라는 리눅스 방을 먼저 만들어요. 4. 처음 켜면 "이 폴더 믿어요?" 묻고, 로그인 방식을 골라요. 5. 설치가 끝나면 /init 으로 프로젝트 설명서를 만들면 더 똑똑해져요.

이 장은 혼자서도 끝까지 따라 할 수 있게 만들었어요. 앞 장(2장 요금제)을 안 봤어도 괜찮지만, 봤다면 로그인 고르는 부분이 더 쉽게 읽혀요.

3.0 시작하기 전에 — 이 장에서 새로 나오는 말들

본격적으로 들어가기 전에, 본문에서 처음 나올 때 한 줄로 풀어줄 말들이에요. 어려운 말로 어려운 말을 설명하지 않을게요.

이 표에 없는 말(Node.js, npm, nvm, WSL 등)은 본문에 처음 나올 때 그 자리에서 풀어줄게요.

3.1 클로드 코드는 쓰던 걸 안 건드려요

이런 적 있죠?

새 프로그램 하나 깔았다가 원래 쓰던 설정이 다 엉켜서, 결국 둘 다 못 쓰게 된 적. 그래서 "새 도구 = 골치 아픈 것"이라고 지레 겁먹기도 하죠.

클로드 코드는 그 걱정을 안 해도 돼요. 쓰던 걸 절대 안 건드리거든요. 이렇게 "있던 환경은 그대로 두고 옆에 얹기만 하는 성질"을 비침투적 통합이라고 불러요. (어렵게 들리지만 뜻은 간단해요. "남의 살림에 손 안 댄다"는 거예요.)

책상 위 스탠드 조명 비유

클로드 코드를 까는 건 책상에 새 스탠드 조명 하나 놓는 것과 같아요. 모니터·키보드·마우스는 그대로 두고, 조명만 켜서 작업이 더 잘 보이게 만드는 거죠. VSCode 쓰던 사람은 VSCode 그대로, IntelliJ 쓰던 사람은 IntelliJ 그대로 쓰면 돼요.

예시 — 오해 vs 진짜

오해: "클로드 코드 깔았으니 VSCode 버리고 터미널만 써야 하나?"
진짜: "VSCode는 그대로 쓰고, 터미널 탭에서 claude를 켜서 거들게 한다."

오해: "개발 방식을 처음부터 다시 배워야 하나?"
진짜: "평소대로 개발하다가, 필요할 때만 claude한테 도와달라고 한다."

이럴 때 이렇게: 친구가 "클로드 코드 깔면 IntelliJ 못 쓰는 거 아냐?"라고 물으면, "아니, IntelliJ 그대로 쓰고 옆에 보조로 켜는 거야"라고 답해주면 돼요.

3.2 설치 전 준비물 — Node.js와 npm

이런 적 있죠?

게임을 받았는데 "실행하려면 이 프로그램이 먼저 필요합니다"라며 안 켜진 적. 클로드 코드도 똑같아요. 먼저 깔아둬야 하는 바탕 프로그램이 있어요.

그게 Node.js예요. Node.js는 한 문장으로, "원래 웹 브라우저 안에서만 돌던 자바스크립트라는 언어를, 브라우저 밖에서도 돌게 해주는 바탕 프로그램"이에요. 일상 비유로는, DVD를 틀려면 있어야 하는 DVD 플레이어 같은 거예요. 클로드 코드를 틀려면 Node.js가 먼저 있어야 해요.

그리고 Node.js를 깔면 npm이 같이 따라와요. npm은 한 문장으로, "누가 미리 만들어 둔 프로그램 묶음(패키지)을 받아서 깔아주는 심부름꾼"이에요. 일상 비유로는, 게임을 받게 해주는 스팀(Steam) 같은 다운로드 가게예요. 클로드 코드도 이 npm으로 설치해요.

준비됐는지 확인하는 법

설치가 됐는지는 터미널에 짧은 명령 두 줄로 확인해요. (터미널은 글자로 명령하는 검은 창이라고 했죠. 버튼 대신 쪽지로 부탁하는 창구예요.)

node --version    # v22.17.1 처럼 버전이 뜨면 준비 끝
npm --version     # 10.9.2 처럼 버전이 뜨면 준비 끝

여기 적힌 v22.17.1, 10.9.2 같은 숫자는 원서/노트 기준 예시예요. 여러분 화면엔 다른 숫자가 떠도 정상이에요. 숫자가 뜨기만 하면 성공이에요.

잘못된 예: node --version 쳤더니 "command not found"
   → Node.js가 아직 안 깔린 거예요. 먼저 Node.js부터 설치하세요.

올바른 예: node --version 쳤더니 "v22.17.1" 같은 숫자가 나옴
   → 준비 끝. 다음 단계로 가면 돼요.

3.3 macOS에 설치하기 — 곧장 세 단계

이런 적 있죠?

앱 하나 깔 때 "기반 프로그램 받고 → 설치 도구로 깔고 → 실행"이라는 흐름, 익숙하죠. macOS 설치도 딱 그 흐름이에요. 새 앱 3단계 설치라고 생각하면 돼요.

비유: 게임 하나 하려면 ① 스팀을 깔고 ② 스팀에서 게임을 받고 ③ 게임을 켜잖아요. 클로드 코드도 ① Node.js 깔고 ② npm으로 받고 ③ claude로 켜요. 똑같은 순서예요.

안전한 길 — 기본 설치 순서

1단계: Node.js 설치

# nodejs.org/ko/download 에 들어가서 macOS Installer(.pkg) 받기
# 받은 파일 더블클릭 → Continue 누르며 진행 → 설치 끝

# 잘 깔렸는지 확인
node --version    # v22.17.1 같은 숫자 나오면 성공
npm --version     # 10.9.2 같은 숫자 나오면 성공

여기서 .pkg는 macOS용 "더블클릭하면 깔리는 설치 파일"이에요.

2단계: 클로드 코드 설치

npm install -g @anthropic-ai/claude-code

이 한 줄을 풀어보면요. npm은 아까 그 심부름꾼이고요. install은 "깔아줘"라는 뜻이에요. -g는 "전역으로"라는 뜻인데, 컴퓨터 어디서든 부를 수 있게 깔라는 거예요. (집 어디서든 쓰는 공용 리모컨처럼요.) @anthropic-ai/claude-code 는 받을 프로그램의 정확한 이름표예요.

3단계: 실행 확인

claude
# 프롬프트 창(글자 입력하는 칸)이 뜨면 성공!

잘못된 예(권한 오류): npm install 했더니 권한 때문에 막힘
   → sudo npm install -g @anthropic-ai/claude-code 처럼 앞에 sudo를 붙여요.
     sudo는 "관리자 권한으로 해줘"라는 뜻이에요. (관리자 카드키로 잠긴 문 여는 셈)

올바른 예: claude 쳤더니 글자 입력 칸이 뜸 → 설치 성공

이럴 때 이렇게: 2단계에서 빨간 권한 오류가 떴다면, 같은 명령 앞에 sudo만 붙여 다시 실행해 보세요.

한 걸음 더 ▸ macOS에서는 Homebrew라는 다른 설치 방법도 있어요. Homebrew는 macOS용 프로그램들을 한곳에서 관리해주는 가게 같은 도구예요. 다만 Homebrew 자체를 따로 깔아야 해서, 처음이라면 위의 공식 .pkg 방법이 제일 쉬워요. 지금은 "그런 길도 있구나" 정도만 알면 충분해요.

3.4 Windows에 설치하기 — 먼저 WSL부터

이런 적 있죠?

Windows에서 안드로이드 앱을 돌리려고 했더니, 에뮬레이터부터 깔라고 한 적 있죠. "안드로이드 앱은 안드로이드에서 도는 거"라서 그래요.

클로드 코드도 비슷해요. 클로드 코드는 리눅스라는 환경에서 도는 도구라, Windows에서 바로는 안 돌아가요. 그래서 Windows 안에 작은 리눅스 방을 하나 만들어요. 그 방을 만들어주는 도구가 WSL이에요. WSL은 한 문장으로, "Windows 안에서 리눅스를 돌게 해주는 기능"이에요. (리눅스는 macOS·Windows 같은 또 다른 운영체제 종류라고만 알면 돼요.)

비유: Windows라는 큰 집 안에, 리눅스라는 작은 방을 하나 만든다고 생각하세요. 클로드 코드는 그 리눅스 방 안에 들여놓고, 거기서 설치하고 거기서 켜요.

안전한 길 — 설치 순서

1단계: WSL 설치 (파워셸을 관리자 권한으로 열고)

파워셸은 Windows에 기본으로 있는 터미널이에요. 글자로 명령하는 검은 창이죠.

wsl --install
# 설치가 끝나면 반드시 컴퓨터를 재시작하세요!

2단계: WSL 실행 & 첫 설정

# 재시작하면 Ubuntu(리눅스의 한 종류)가 자동으로 깔려요
# 리눅스에서 쓸 계정 이름과 비밀번호를 정해 입력해요

# 그다음 파워셸에서
cd \
wsl --update
wsl -d ubuntu

여기서 당황 포인트 하나. 비밀번호를 칠 때 화면에 글자가 하나도 안 보여요. 별표(*)조차 안 떠요. 고장 난 게 아니에요. 리눅스는 보안상 비밀번호를 일부러 안 보여줘요. 그냥 또박또박 치고 엔터 누르면 돼요.

3단계: Node.js 설치 (nvm 사용)

리눅스 방 안에서는 macOS처럼 .pkg를 더블클릭할 수 없어요. 그래서 글자 명령으로 Node.js를 깔아주는 도구인 nvm을 써요. nvm은 한 문장으로, "Node.js를 여러 버전 깔고 갈아끼울 수 있게 해주는 관리 도구"예요. (옷장에 여러 벌 걸어두고 골라 입는 것처럼, Node.js 버전을 골라 쓸 수 있어요.)

# nvm 받아서 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Node.js 22 버전 설치
nvm install 22

# 잘 깔렸는지 확인
node -v    # v22.17.1 나오면 성공
npm -v     # 10.9.2 나오면 성공

여기 적힌 v0.40.1, 22 같은 숫자는 원서/노트 기준 예시예요. 최신 값은 공식 문서(클로드 코드 공식 문서, nvm 공식 저장소)에서 확인하세요.

4단계: 클로드 코드 설치 & 실행

npm install -g @anthropic-ai/claude-code
claude    # 프롬프트 창이 뜨면 성공!

설치 명령은 macOS와 똑같아요. 다른 점은 "리눅스 방 안에서" 한다는 것뿐이에요.

잘못된 예: Windows 파워셸에서 바로 npm install -g @anthropic-ai/claude-code 실행
   → 안 돼요. 반드시 WSL(리눅스 방) 안에서 깔아야 해요.

잘못된 예: C:\Windows\system32 폴더에서 wsl -d ubuntu 실행 → 경로 오류 날 수 있음
   → 먼저 cd \ 로 C:\ 맨 위 칸으로 옮긴 뒤 wsl -d ubuntu 를 실행하세요.

당황 포인트: 비밀번호 칠 때 화면에 아무것도 안 보임
   → 정상이에요. 리눅스는 비밀번호를 일부러 안 보여줘요. 그냥 치면 돼요.

이럴 때 이렇게: 파워셸에 명령을 쳤는데 자꾸 오류가 난다면, "지금 내가 친 명령이 Windows 쪽이어야 하나, 리눅스 방 안쪽이어야 하나?"부터 헷갈리는 게 대부분이에요. 설치 명령(npm install ...)은 무조건 리눅스 방 안에서예요.

macOS와 Windows, 뭐가 다를까

한 걸음 더 ▸ nvm을 쓰면 좋은 점이 더 있어요. ① nvm install 20, nvm install 22 처럼 여러 버전을 깔고 골라 쓸 수 있어요. ② macOS에서도 nvm을 쓸 수 있어서, 팀원끼리 같은 버전 맞추기가 쉬워요. ③ 전역 설치할 때 생기는 권한 문제(아까 sudo 붙이던 그것)를 피하기 좋아요. 처음엔 그냥 nvm install 22 한 줄만 알아도 충분해요. 나머지는 나중에 필요할 때 보면 돼요.

3.5 처음 켰을 때 — 폴더 신뢰와 로그인

이런 적 있죠?

새 앱을 처음 켜면 "사진 접근을 허용할까요?", "로그인 방법을 고르세요" 같은 걸 먼저 묻죠. 클로드 코드도 똑같이, 처음 켜면 두 가지를 먼저 물어봐요.

비유: 새집에 처음 들어가는 것 같아요. ① "이 집(폴더)에 들어가도 돼요?" 확인받고 → ② "열쇠는 뭐로 쓸래요?" 정하고 → ③ 들어가서 작업 시작.

첫 번째 질문 — 이 폴더 믿어요? (폴더 신뢰)

클로드 코드는 폴더 안의 파일을 읽고 고칠 수 있어요. 그래서 처음엔 "여기 파일들 만져도 돼요?"라고 꼭 한 번 물어봐요. 이걸 폴더 신뢰라고 해요. (낯선 집에 들어가기 전 "들어가도 되나요?" 묻는 예의 같은 거예요. 보안을 위한 절차죠.)

Do you trust the files in this folder?
/Users/jihochoi/Desktop

> 1. Yes, proceed    ← 이걸 골라요
  2. No, exit

잘못된 예: "No, exit"를 고름 → 클로드 코드가 그냥 꺼져버려요.
올바른 예: "Yes, proceed"를 고름 → 정상으로 다음 단계 진행.

두 번째 질문 — 로그인 방식 (구독 vs API)

다음은 로그인 방식을 골라요. 두 가지 중 하나예요.

Select login method:
> 1. Claude account with subscription     ← 구독자(월정액)용
     Starting at $20/mo for Pro, $100/mo for Max

  2. Anthropic Console account             ← API(쓴 만큼 내기)용
     API usage billing

1번은 매달 정해진 돈을 내는 구독 방식이에요. (예: Pro, Max 같은 요금제) 2번은 쓴 만큼만 내는 방식이에요. (이걸 종량제라고 해요. 전기·수도처럼 쓴 만큼 요금이 나와요.)

여기 적힌 $20, $100 같은 숫자는 원서/노트 기준 예시예요. 요금·요금제 이름은 시간이 지나면 바뀔 수 있으니, 최신 값은 공식 문서(클로드 코드 공식 문서)에서 꼭 확인하세요.

어느 걸 고를지 헷갈리면, 입문자는 보통 1번(구독)이 마음 편해요. 2장(요금제)을 봤다면 거기서 본 Pro/Max 차이가 그대로 여기 1번이에요.

글자가 깨져 보일 때: 터미널 글꼴이 특수문자를 못 그리는 경우예요.
   → 파워셸 속성에서 글꼴을 Consolas, D2Coding 같은 걸로 바꿔보세요.

세 번째 — 프롬프트 창이 뜨면 끝

두 질문에 답하고 나면, 글자를 입력하는 칸(>)이 떠요. 여기에 부탁을 적어 넣으면 클로드 코드가 일을 시작해요. 여기까지 왔으면 설치·설정 끝이에요.

이럴 때 이렇게: claude를 켰는데 글자 입력 칸이 안 보인다면, 대개 위 두 질문 중 하나에서 멈춰 있는 거예요. 질문에 답(특히 "Yes, proceed")부터 해주세요.

3.6 설치 후 첫 꿀팁 두 가지

이런 적 있죠?

배경 설명 하나 없이 일을 시키면, 상대가 엉뚱하게 알아듣는 적 있죠. 클로드 코드도 마찬가지예요. 프로젝트 사정을 모르면 답이 좀 빗나가요. 그래서 처음 켜면 이런 안내가 떠요.

Tips for getting started:
1. Run /init to create a CLAUDE.md file with instructions for Claude
2. Run /terminal-setup to set up terminal integration
3. Use Claude to help with file analysis, editing, bash commands and git
4. Be as specific as you would with another engineer for the best results

꿀팁 1 — /init 으로 프로젝트 설명서 만들기

/init은 클로드 코드 안에서 치는 내장 명령이에요. (앞에 슬래시 / 가 붙어요.) 이걸 치면 CLAUDE.md라는 파일을 자동으로 만들어줘요. CLAUDE.md는 한 문장으로, "이 프로젝트가 뭐고 어떤 규칙으로 일하는지 적어둔 설명서"예요. 클로드 코드는 이 설명서를 읽고 프로젝트 사정을 파악해서 더 정확하게 답해요.

잘못된 예: 설명 하나 없이 곧바로 질문 → 프로젝트 사정을 몰라 답이 빗나감.
올바른 예: 먼저 /init 실행 → CLAUDE.md 생성 → 클로드가 규칙을 알고 더 정확히 답함.

이럴 때 이렇게: 새 프로젝트 폴더에서 클로드 코드를 처음 켰다면, 다른 거 하기 전에 /init부터 한 번 쳐주세요.

꿀팁 2 — /terminal-setup 으로 터미널 손발 맞추기

/terminal-setup도 슬래시로 시작하는 내장 명령이에요. 터미널과 클로드 코드가 더 잘 맞물려 돌게 단축키 같은 걸 설정해줘요. (예: 줄바꿈 단축키 같은 편의 기능이요.) 지금은 "터미널을 더 편하게 쓰게 해주는 설정"이라고만 알아도 충분해요.

3.7 한눈에 보는 전체 흐름

지금까지 한 걸 한 장으로 모으면 이래요.

[설치 시작]
   │
   ├─ macOS면 →  Node.js(.pkg) 설치 → 확인 → npm install -g 클로드 코드 → claude
   │
   └─ Windows면 → WSL 설치 → 재시작 → 리눅스 방 진입
                  → nvm으로 Node.js 설치 → npm install -g 클로드 코드 → claude

[claude 첫 실행]
   │
   ├─ ① 폴더 신뢰: "Yes, proceed" 선택
   ├─ ② 로그인: 구독(1번) 또는 API(2번) 선택
   └─ ③ 프롬프트 창(>) 뜨면 완료!

[더 잘 쓰려면]
   └─ /init 으로 CLAUDE.md 만들기 + /terminal-setup 으로 터미널 설정

3.8 스스로 확인하기 (연습문제)

문제 1 (기본)

macOS에서 클로드 코드를 깔기 전에 먼저 준비해야 하는 프로그램 두 가지는 무엇인가요?

문제 2 (기본)

Windows에서 클로드 코드를 바로 못 쓰고 WSL을 먼저 까는 이유를 한 문장으로 설명하세요.

문제 3 (중급)

Windows에서 WSL 설치 직후 비밀번호를 칠 때 화면에 글자가 안 보여요. 어떻게 해야 하나요?

문제 4 (중급)

처음 claude를 켰을 때 나오는 "폴더 신뢰" 질문은 무엇이고, 무엇을 골라야 하나요?

문제 5 (실습)

자기 컴퓨터(macOS 또는 Windows)에 클로드 코드를 깔고, claude로 켜서 폴더 신뢰와 로그인까지 끝내 보세요. 그리고 /init 까지 한 번 실행해 보세요.

참고 자료

요금·요금제 이름·버전 숫자처럼 시간이 지나면 바뀌는 값들은 이 책의 예시일 뿐이에요. 실제로 깔 때는 위 공식 문서에서 지금 값을 한 번 확인하면 가장 안전해요.

다음 장 예고: 다음 장에서는 깔아둔 클로드 코드를 실제로 어떻게 쓰는지 살펴봐요. 지금 그 내용을 몰라도 이 장을 따라오는 데는 아무 문제 없어요.